home *** CD-ROM | disk | FTP | other *** search
/ JCSM Shareware Collection 1996 September / JCSM Shareware Collection (JCS Distribution) (September 1996).ISO / prgtools / 11730a01.ziv / VTOOLS21.EXE / MCGALIB.DOC < prev    next >
Text File  |  1994-05-30  |  9KB  |  272 lines
  1. ┌──────────────────────┐
  2. │ THE MCGA-VGA LIBRARY │
  3. └──────────────────────┘
  4.  
  5. These  functions  are  for  the  VGA  19, 320 x 200, 256 colors
  6. screen. To see how to use  the  sprite  functions,  look at the
  7. EXAMPLE.C listing, and read explanations on EXAMPLE program la-
  8. ter also...
  9.  
  10. Functions supported are these:
  11. - Set a screen mode.
  12. - Display a text string.
  13. - Clear the screen.
  14. - Put a pixel.
  15. - Get a pixel color.
  16. - Draw line, rectangle.
  17. - Create colors.
  18. - Using several palettes.
  19. - Set a window.
  20. - Get a block of screen.
  21. - Put a block on screen.
  22. - Fill a rectangle.
  23. - Put a 16 color icon on screen.
  24. - Put 256 color sprites:
  25.    * In XOR mode.
  26.    * In overwriting mode.
  27.    * In copy mode.
  28. - Functions for special effects.
  29. - Scrolling hardware or software.
  30.  
  31. The variables of the library:
  32.  
  33. VARIABLES FOR GRAPHICAL WINDOW
  34. unsigned int XL=0;
  35. unsigned int XR=319;
  36. unsigned int YB=0;
  37. unsigned int YT=199;
  38.  
  39. VARIABLE FOR REAL OR VIRTUAL SCREEN
  40. unsigned int VGASCREEN=0xA000;
  41.   The  default value (0xA000) is the segment adress of the real
  42. screen,  one  changes  segment  to use a virtual screen, offset
  43. must be 0.
  44.  
  45. extern unsigned char TEXTCOLOR;  Color for text display.
  46. extern unsigned long *SPVECTOR;  Pointer on sprites' addresses.
  47. extern char *SPCODE;             Pointer on start of sprites'
  48.    code.
  49.  
  50.  
  51. The functions of the library:
  52.  
  53. void selectscreen(int mode);
  54.   To change the screen mode: 19 for MCGA screen, 3 for text screen.
  55.  
  56. char *getspadr(int number);
  57.   Returns  address of a sprite by sending its number in the ta-
  58. ble,  that  is in the range 1..N, N being number of sprites in
  59. the table.
  60.  
  61. void window19(int left, int bottom, int right, int top);
  62.   Set  a  graphical  window  inside the screen. Left = 0..319,
  63. right = 0..319, bottom = 0..199, top = 0..199.
  64.  
  65. void DOSwrite(int column, int line, char *text);
  66.   Put a string on screen. Column = 1..40, line = 1..25.  Color
  67. according to the TEXTCOLOR variable.
  68.  
  69. void cls19(int color);
  70.   Clear the screen with a color among 256.
  71.  
  72. void sprite256(int x, int y, char *adr);
  73.   Put  a  256  colors sprite on scenery, without   erasing the
  74. background. Address is either an  absolute address or the GETS-
  75. PADR function with the sprite number as parameter.
  76.   Ex.:  sprite256( 5, 18, getspadr( 3 ));
  77. This displays the third sprite in table at x = 5, y = 18.
  78.  
  79. void csprite256(int x, int y, char *adr);
  80.   Put  a sprite with its background on the screen. That erases
  81. the scenery. It's very fast and serves to make scenery.
  82.  
  83. void csprite256c(int x,int y,char *adr);
  84.    As csprite256 but inside the user-defined window
  85.  
  86. void xsprite256(int x, int y, char *adr);
  87.   Display  a  sprite in XOR mode, exclusive or. This change the
  88. colors. By  displaying  again the sprite one restore the back-
  89. ground.
  90.  
  91. void sprite(int number, int x, int y, unsigned char mode);
  92.   Generical function that calls other sprite functions accor-
  93. ding to the chosen mode:
  94.      0 = COPY.
  95.      4 = overwriting.
  96.  
  97. void  getblock(int  left,  int  bottom, int right, int top,
  98. char *adr);
  99.   Get a block of the screen to the adress This requires an even
  100. width.  And  one  must  first  allocate a memory buffer at  adr
  101. (with the malloc function in C language).
  102.  
  103. void putblock(int x, int y, char *adr);
  104.   Put a block saved with getblock on the screen.
  105.  
  106. void icon19(int x, int y, char *adr);
  107.   Put a 16 color icon on the screen. An icon displays color 0
  108. that  is the black color number, and don't display color 9 that
  109. serves to background. It can be made with the k, i or j command
  110. of MegaSprites.
  111.  
  112. void writeRGB(char *paladr);
  113.   Set  a  256 color palette from a file of 768 values, pre-
  114. viously loaded in memory at paladr.
  115.  
  116. void writecolor(int colnum, int r, int g, int b);
  117.   Create a new color # colnum with three red, green,  and blue
  118. values, that are in range 0..63.
  119.  
  120. void setpix256(int x, int y, unsigned char color);
  121.   Put a pixel at x, y.
  122.  
  123. int getpix256(int x, int y);
  124.   Get the color of pixel at x, y.
  125.  
  126. void  line256(int x, int y, int x2, int y2, unsigned char color);
  127.  Draw a line from starting point at x, y to ending point at x2, y2.
  128.  
  129. void rectangle(int left,int botton,int right,int top);
  130.   Draw a rectangle
  131.  
  132. void fillblock(int l, int b, int r, int h, int color);
  133.   Fill a rectangle defined by l, b, r, b (left, bottom, right, top)
  134. with a color among 256.
  135.  
  136. void synchro();
  137.   Wait for a screen refresh.
  138.  
  139. void appear(char *palette);
  140.   Make the screen slowly appearing.
  141.  
  142. void disappear(char *palette);
  143.   Make the screen slowly disappearing.
  144.  
  145. void MCGAscroll(char decal);
  146.   Full screen scolling, does a BIOS call.
  147.  
  148. void scroll(int dir,int step);
  149.    Scrolling of the user-defined window
  150.    Step is the number of pixels to move
  151.    Dir is the direction:
  152.         1 = up
  153.         2 = right
  154.         3 = down
  155.         4 = left
  156.  
  157.  
  158.  
  159. MCGALIB.OBJ
  160.  
  161. MCGALIB.OBJ holds all the functions detailed above. It's an as-
  162. sembly  80286  set  of functions that can be used with any lan-
  163. guage and compiler.
  164. The way to use this assembly module depends of the compiler and
  165. must to be explained in its manual.
  166.  
  167. This  module  is assembled for LARGE MODEL, CASE-SENSITIVE, and
  168. symbols  are  prefixed  by the '_' letter, that requires either
  169. you  set  the appropriate option to your linker, or you prefixe
  170. the functions with '_' at the call.
  171.  
  172. For example:          sprite(x, y, adr)
  173. becomes              _sprite(x, y, adr).
  174.  
  175. The MCGALIB.H file can be included in C files, it is not requi-
  176. red however.
  177. The  source code MCGALIB.C or MCGALIB.ASM that is provided if a
  178. registered version can so be included in a C or assembly module
  179. or translated to another language.
  180.  
  181.  
  182. ┌─────────────────────┐
  183. │ THE EXAMPLE PROGRAM │
  184. └─────────────────────┘
  185.  
  186. Files used by the program:
  187.  
  188. DEMO2.SPR            File of sprites.
  189. DEMO2.AUT            File of an automaton.
  190. EXAMPLE.C            C ANSI source file for example of use.
  191. EXAMPLE.EXE          The executable.
  192. EXAMPLE.PRJ          A TC 2.0 project example.
  193. MCGALIB.OBJ          Assembly 80286 library of graphical and
  194.                      sprite functions.
  195. MCGALIB.H            Header file of MCGALIB.OBJ for C compilers.
  196.  
  197. The EXAMPLE program is a very simple program to show how to use
  198. sprites and automaton. It uses MCGALIB.OBJ and also it includes
  199. all necessary functions for sprite management: loading sprite,
  200. converting addresses after loading, making scenery, etc..
  201.  
  202.  
  203. Variables for sprite using:
  204.  
  205. FILE *FP;             Used by file functions.
  206. int *AUTOMATON;       Pointer on a buffer for automaton.
  207. char *BLOCKSAVE;      Pointer on a buffer for screen block.
  208. int AUTMAX;           Number of entries in automaton.
  209. int SPRMAX;           Number of sprites in table.
  210.  
  211.  
  212. Fonctions for sprite using:
  213.  
  214. void outtextf(int x,int y,char *fmt, ... );
  215.     Display a formatted text string at x, y. As printf for gra-
  216. phical screen.
  217.      x=0..40
  218.      y=0..24
  219.  
  220. int autread(int i);
  221.     Function  to  read  frame i of loaded automaton, return the
  222. sprite number to this frame.
  223.  
  224. int getcode(int n);
  225.     Function that returns code of format of sprite #n.
  226.  
  227.  
  228. Function for loading files:
  229.  
  230. void changext(char *name,char *ext);
  231.     Add  or  replace  extension  of filename by the proper one.
  232. Assume  size  of  variable names is large enough to handle a 13
  233. characters long string.
  234.  
  235. int bload(char *fname,char *adr,int siz);
  236.    Load any binary file. Return 1 if OK, 0 otherwise.
  237.  
  238. int autload(char *aname);
  239.    Load automaton "aname" at AUTOMATON location. Assume AUTOMA-
  240. TON  points  out a memory buffer allocated with function of the
  241. language.
  242.  
  243. int sprload(char *spname);
  244.   Load the file of sprites "spname", at SPVECTOR location.  SP-
  245. VECTOR  is a pointer defined in MCGALIB, and it must be alloca-
  246. ted before loading sprites into memory. The function is shorte-
  247. ned  to  load  file until 64 Kb long if a unregistered version,
  248. and it is the same as that of VTools if the registered version.
  249. It convert relative addresses to absolute ones.
  250.   Return 1 if OK, 0 otherwise.
  251.   When returning, SPVECTOR points out the table of adresses  of
  252. the sprites, and SPCODE points out the images.
  253.  
  254.  
  255. The main loop of the program:
  256.  
  257.  This  program  is  a  short example to show how to use 256 co-
  258. lor sprites on a scenery without erasing the scenery.
  259. The scenery is a single sprite that covers background. The main
  260. iteration  saves  the  block of screen where animation is done,
  261. puts the sprite, restores the screen, then one repeats the ope-
  262. ration  at  the  next  location, and so on... Even if it's very
  263. simple,  this example holds all that is required for a strategy
  264. or  role-playing game. To make an arcade game, the color planes
  265. principle  is required and that is for the PLIB library and its
  266. example...
  267.  
  268.  
  269.  
  270.  
  271.  
  272.